﻿// HSS.Interlink.IUploadClient.cs
// ----------------------------------------------------------------------------
// Licensed under the MIT license (http://www.opensource.org/licenses/mit-license.html)
// ----------------------------------------------------------------------------
// HighSpeed-Solutions, LLC
// Copyright (c) 2001-2012
// ----------------------------------------------------------------------------
// File:       IUploadClient.cs
// Author:     HSS\gbanta
// Created:    01/17/2012
// Modified:   01/17/2012
// ----------------------------------------------------------------------------
namespace HSS.Interlink
{
	#region Using Directives
	using System;
	#endregion

	#region IUploadClient
	/// <summary>
	/// Defines the contract for an upload client.
	/// </summary>
	public interface IUploadClient
	{
		#region Events
		/// <summary>
		/// Occurs when an asynchronous upload operation successfully transfers some or all of the data.
		/// </summary>
		event EventHandler<UploadFileCompletedEventArgs> UploadCompleted;
		/// <summary>
		/// Occurs when an asynchronous upload operation has completed.
		/// </summary>
		event EventHandler<UploadFileProgressEventArgs> UploadProgressChanged;
		#endregion

		#region Properties

		#region Read-Only
		/// <summary>
		/// Gets the name of the file being uploaded.
		/// </summary>
		string FileName { get; }
		/// <summary>
		/// Gets if the upload is currently in progress.
		/// </summary>
		bool IsBusy { get; }
		/// <summary>
		/// Gets or sets the web.config AppSetting Key that specifies the File Handler
		/// for this file upload request.
		/// </summary>
		string ClientConfig { get; }
		/// <summary>
		/// Gets the uri of the upload service.
		/// </summary>
		[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1056:UriPropertiesShouldNotBeStrings")]
		string ServiceUri { get; }
		/// <summary>
		/// Gets the timestamp of when this content began the upload process.
		/// </summary>
		DateTime StartTimestamp { get; }
		/// <summary>
		/// Gets the timestamp of when this content finished the upload process.
		/// </summary>
		DateTime EndTimestamp { get; }
		/// <summary>
		/// Gets the elapsed time of the upload process.
		/// </summary>
		TimeSpan ElapsedTime { get; }
		/// <summary>
		/// Gets the elapsed time of the upload process in Seconds.
		/// </summary>
		double ElapsedSeconds { get; }
		/// <summary>
		/// Gets the estimated transfer rate (Bytes/Sec) of the upload.
		/// </summary>
		double TransferRate { get; }
		/// <summary>
		/// Gets the length of the content being uploaded.
		/// </summary>
		long ContentLength { get; }
		#endregion

		#region Read-Write
		/// <summary>
		/// Gets or sets a <see cref="Boolean"/> value that controls whether default credentials are sent with requests.
		/// </summary>
		bool UseDefaultCredentials { get; set; }
		/// <summary>
		/// Gets or sets the network credentials that are sent to the host and used to authenticate the request.
		/// </summary>
		System.Net.ICredentials Credentials { get; set; }
		#endregion

		#endregion

		#region Methods
		/// <summary>
		/// Initializes the client.
		/// </summary>
		/// <param name="serviceUri">The Uri of the remote service to process the upload request.</param>
		/// <param name="config">Any custom config required for this client.</param>
		/// <param name="allowFileOverwrite">True to overwrite existing files; otherwise False.</param>
		[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings", MessageId = "0#")]
		void Initialize(string serviceUri, string config, bool allowFileOverwrite);
		/// <summary>
		/// Begins uploading the content.
		/// </summary>
		/// <param name="content">The byte array to upload.</param>
		/// <param name="fileName">The name of the file the bytes are being uploaded to.</param>
		void UploadDataAsync(byte[] content, string fileName);
		/// <summary>
		/// Begins uploading the contents.
		/// </summary>
		/// <param name="content">The byte array to upload.</param>
		/// <param name="fileName">The name of the file the bytes are being uploaded to.</param>
		/// <param name="metadata">Optional metadata string containing additional information to send with the file.</param>
		void UploadDataAsync(byte[] content, string fileName, string metadata);
		/// <summary>
		/// Begins uploading the contents.
		/// </summary>
		/// <param name="content">The byte array to upload.</param>
		/// <param name="fileName">The name of the file the bytes are being uploaded to.</param>
		/// <param name="metadata">Optional metadata string containing additional information to send with the file.</param>
		/// <param name="userToken">Optional user state associated with this request.</param>
		void UploadDataAsync(byte[] content, string fileName, string metadata, object userToken);
		/// <summary>
		/// Begins uploading the content.
		/// </summary>
		/// <param name="content">The stream to upload.</param>
		/// <param name="fileName">The name of the file the stream is being uploaded to.</param>
		void UploadStreamAsync(System.IO.Stream content, string fileName);
		/// <summary>
		/// Begins uploading the content.
		/// </summary>
		/// <param name="content">The stream to upload.</param>
		/// <param name="fileName">The name of the file the stream is being uploaded to.</param>
		/// <param name="metadata">Optional metadata string containing additional information to send with the file.</param>
		/// <param name="autoCloseStream">True to close the provided content stream once the upload completes; otherwise false to leave open.</param>
		void UploadStreamAsync(System.IO.Stream content, string fileName, string metadata, bool autoCloseStream);
		/// <summary>
		/// Begins uploading the content.
		/// </summary>
		/// <param name="content">The stream to upload.</param>
		/// <param name="fileName">The name of the file the stream is being uploaded to.</param>
		/// <param name="metadata">Optional metadata string containing additional information to send with the file.</param>
		/// <param name="autoCloseStream">True to close the provided content stream once the upload completes; otherwise false to leave open.</param>
		/// <param name="userToken">Optional user state associated with this request.</param>
		void UploadStreamAsync(System.IO.Stream content, string fileName, string metadata, bool autoCloseStream, object userToken);
		/// <summary>
		/// Begins uploading the contents.
		/// </summary>
		/// <param name="content">The string to upload.</param>
		/// <param name="fileName">The name of the file the string is being uploaded to.</param>
		void UploadStringAsync(string content, string fileName);
		/// <summary>
		/// Begins uploading the contents.
		/// </summary>
		/// <param name="content">The string to upload.</param>
		/// <param name="fileName">The name of the file the string is being uploaded to.</param>
		/// <param name="metadata">Optional metadata string containing additional information to send with the file.</param>
		void UploadStringAsync(string content, string fileName, string metadata);
		/// <summary>
		/// Begins uploading the contents.
		/// </summary>
		/// <param name="content">The string to upload.</param>
		/// <param name="fileName">The name of the file the string is being uploaded to.</param>
		/// <param name="metadata">Optional metadata string containing additional information to send with the file.</param>
		/// <param name="userToken">Optional user state associated with this request.</param>
		void UploadStringAsync(string content, string fileName, string metadata, object userToken);
		/// <summary>
		/// Request to cancel the write operation
		/// </summary>
		void CancelAsync();
		#endregion
	}
	#endregion
}